Roller

	This plug-in is written in Python 2.7 for GIMP v2.10. Roller is designed to create image compositions like wallpaper, image boards, collages, etc. Roller 1 through 5 presets are incompatible with Roller 6.

	Please note that Roller requires access to the hard drive, its installation folder to be exact, in order to save preset data. If Roller can't save a preset, then the plugin will shutdown, and spit out an error.

Basics

	Steps

	Roller breaks a render into steps. Steps are how an option group produces layer output. Global, Gradient Light, Backdrop are examples of an option group, each having a step. Some steps have a sub-step. A sub-step will produce an additional layer in the step's layer group.

    A View Button
    
    A view button when activated causes steps to be processed. There are two basic view types: Plan and a work-in-progress (work). For each basic view, there are two process options, a partial and a complete view. For planning, draft produces a partial plan. A partial view ends its output on the option group visible in the main window. When working, the Peek option is the partial option, while an activated Preview makes a complete view.

	Composition

	Roller creates layers like a pancake robot in a sci-fi movie, but the Backdrop Image layer and the Gradient Light output deserve a mention.

	Every composition has a Backing layer. This layer serves as a backdrop for the composition and may provide material for a Backdrop Style. Many Backdrop Styles depend on the pixels in the Backdrop Image layer. A style's tool-tip will indicate this dependency.

	Gradient Light is a gradient that is used in multiple parts of a render. It's purpose is to simulate a light source or an environment, but it has other uses, such as unifying a composition.

Model

	Each model offers unique possibilities for composing. Roller 6 has several models: Table, Cell, Stack, Box, Pyramid, and Sidewalk. Models share some common characteristics. They all have a Property option group, and a Cell/Type option group.

    After creating a model, steps need to be added to the navigation tree in order to produce layer output. Select the Model Step button in the Model group to choose steps.

	Table
	
	The Table model has two branches: Canvas and Cell. The Canvas branch has options for modifying the canvas rectangle. The Cell branch is very much like the Canvas branch, except for the options apply to a  user-defined cell rectangle.

	Grid-type models divide the canvas into a grid defined by row and column counts. Row and column intersections form a cell. The main window options apply to the entire grid. If a single cell needs to modified, the Per option is used. Table, Box, and Sidewalk are grid-type models.

	The Per option when selected provides access to a grid layout which in turn opens a Cell Editor. The Cell/Type/Per option however only has a merge cell layout.

	Cell
	
	The Cell model has one branch: Cell. A Rectangle option defines a single cell rectangle for its output.

	Stack
	
	A Stack model has one branch, and like Cell, uses a Rectangle option to define its first cell. When Stack has more than one cell, the Add Offset X and Add Offset Y options modify the additional cell rectangle positions. For each cell after the first, the offsets are added to the previous cell rectangle's position to determine the next cell's topleft position.

	Box
	
	The Box model has three branches: Canvas, Cell, and Face. The Box grid is the same grid as the Table's hexagon-shaped cell. It's a double-spaced grid where every other cell is valid. A Face option group applies itself to the three faces on the Box.

	Pyramid

	A Pyramid model has two branches, Canvas and Cell. A cell is assigned with a row and its column count. Cell size is calculated evenly where each cell is gets an equal share in its scope. The wide end of the Pyramid is row one's location. If the Pyramid is facing up, then row one is at the bottom. If the Pyramid is facing down, row one is at the top of the Pyramid.

	Sidewalk

	A Pyramid model has three branches, Canvas, Cell, and Facing. Cells are arranged in a rectangular ring. The The Facing output is placed either inward or outward from the center of the cell ring. Cells on a side have perpendicular placed output, while the corner cells output direction is determined by the shape of the cell ring.

Model Step

	Model Steps are option groups visible in the user interface. The steps are processed from the top-down and left-to-right as reflected in the navigation tree. Output processing starts at the bottom of the Layers dock and ends at the top which is the reverse order of the navigation tree.

	Model Steps have three different states: excluded, available, and shelved. A Model Step's life management is set from the Model/New/Define Model dialog or the Model/Revise dialog. Available Model Steps are visible in the user interface. A Model Step can be shelved using the Model Step dialog. A shelved Model Step retains its option values between sessions while an excluded Model Step does not.

Insight

	Steps Preset
	
	This option group is found on the trunk of the navigation tree. It's positioned at the bottom of the branch list. Its value is all the available and shelved Model Step in the current Roller window. When the Roller plug-in starts it seeks and loads a "Last Used" Steps Preset. Saving a Last Used Steps Preset during a session run is advisable if you want the settings to load on your next run. Keep it mind that Roller writes this file on an Accept command from its main window.

	Cell Rectangle

	Every cell has a rectangle that defines a cell bounds. A cell's shape its determined by this limitation. However, there are other rectangles that effect how the final cell output, such as, the Shift and Margin options.

	Shift

	The Shift options adjust a rectangle's size and position. There are Canvas and Cell versions of Shift. The Cell version may have a Per option which can change a single cell's rectangle.
	
	Margin

	Margin options apply inside a rectangle. They produce a pocket rectangle. An Image option group is always limited to the pocket, but other option groups have an Obey Margins options which, when off, causes the output to ignore the pocket limitation.

	Cell Shape
		
	A cell shape has two variations. The cell rectangle defines the original shape of the cell. If margins apply, then there is an additional cell shape created. Option groups will use one or the other cell shape when masking and sizing layer output.

	Image Mold

	The image mold is a process that ensures that an image fits inside a pocket. If an image is larger than its pocket, the image may be scaled down depending on the Resize Method. On the other hand, depending on the Resize Method and image justification, an image may be enlarged in order to fill a pocket.

	Roller can use open images in GIMP when Roller starts, but only for making copies. Roller never does anything else with an open or file image. The only image in which Roller manipulates is its rendered image.

	View Button

	The view buttons are on the bottom of the main window and a satellite dialog. Activating a button will cause Roller to produce layer output. After the button's action has completed, the button will turn gray. If Roller should crash, then a view button will be gray, but layer output will be incomplete.

	Background

	There are two options that take a snapshot of their background layers: Mean Color and Below. Both options make a snapshot by hiding the layers above and their own layer group. Whenever their background changes, their output will also update.

	Main and Per Output

	Main output is produced by an option based in the main window. If main output is multi-cell, the cell production is combined or merged into one layer.

	Per output is produced by customizing an individual cell/face/facing. A Per output is separate from the main output.


Adding Frame Images to the Frame Folder
		
	During start-up, Roller compiles a list of '.png' file types from Roller's Frame folder. You can add additional frames to this folder. In order to add your own frames, they must be the '.png' file type. The frames are used solely by the Frame/Over option. My gratitude goes to dinasset from 'gimpchat.com' for sharing the provided frame files.

Errors And Limitations

	* If an image is referenced from a File or Folder image source is displaying black instead of image material, try converting the image to GIMP's sRGB color profile prior to running Roller.

	* Opening and closing images in GIMP while Roller is open may make Roller unstable.

	* Putting too many rows and columns into a composition grid may result in a crash. GTK has its limitations, and Roller doesn't compensate for a grossly large scale. The Merge Cells window may come to a crawl when drawing a multitude of cells. I was able to create a grid of 15 rows and 15 columns without too much of a delay. So patience may be in order if you wish to create a larger grid of cells.

	* I recommend having the Layers Dock visible while running Roller as this dock will show GIMP working.

	* Roller doesn't save images. Roller does save Preset files inside the Roller/Resources folder.

	* Running two Roller scripts simultaneously is not supported.

	* When the script is run for the first time, Python creates ".pyc" type files within the Roller/Resource/Module folder. These files help the code run faster in the Python interpreter. The files are re-created if they go missing, so have no worries about deleting them.

	* Some dynamic brushes, when applied as brush stroke, with Roller brush output may not work.

	* Roller uses the clipboard to make image snapshots. If there is another background process also using the clipboard, then this can cause the copy and paste operation to fail resulting in a completely black copy and/or a possible Roller crash.

	* Testing and designing a composition can be sped up in several ways.
		1) Reduce the size of the render during testing.
		2) Turn off unused option groups.
		3) Move steps to the model list shelf.
		4) Be mindful of the background update layers: Mean Color and Below which update when their backgrounds change.

	* It's safe to adjust layer opacity and mode in the Layers Dock while Roller is idle. However, Roller typically won't see these kind of changes during its processing.

	* The Backdrop Style/Triangle Reverb may produce an irregular result if the Global/Work-in-Progress scale is too small. 

Special Thanks

	Many thanks to the free programs Notepad++ (for easy editing), Visual Studio Code (for syntax checking), and PyCharm (for detailed code analysis). Each is a great Python code editor. Also, I would like to give a special thanks to every GIMP plug-in author for sharing their inspirational work.

	- Charles Bartley
	October 23, 2024
